Skip to content

Conversation

@xylar
Copy link
Contributor

@xylar xylar commented Jul 20, 2025

This pull request focuses on improving the documentation structure, readability, and accuracy for the E3SM-Unified project. Key updates include the addition of new sections, restructuring existing content, and refining package details for clarity.

Documentation Restructuring and Additions:

  • Created new sections for "Release Workflow" (docs/releasing/index.md), "Creating Release Candidates" (docs/releasing/creating-rcs/index.md), and "Deployment and Testing" (docs/releasing/testing/index.md) to better organize the release process and testing documentation. [1] [2] [3]
  • Moved and updated content from standalone markdown files (e.g., creating-rcs.md, testing/overview.md) into the newly created sections, improving navigation and clarity. [1] [2]

Refinement of Package Details:

  • Updated the package catalog in docs/packages.md to split version constraints for Python versions into separate rows, enhancing readability. Additional explanatory text was added for better understanding of the table format. [1] [2] [3] [4]

Navigation and Linking Improvements:

  • Fixed or updated internal links across multiple files to reflect the new structure, ensuring accurate navigation (e.g., linking to creating-rcs/overview.md instead of creating-rcs.md). [1] [2] [3] [4]

Build Process Enhancements:

  • Enhanced the Sphinx build process in docs/Makefile by adding stricter error handling (-nW --keep-going) to ensure that warnings are treated as errors.

Minor Content Updates:

  • Adjusted the table of contents depth in docs/index.md for better focus and removed outdated or redundant entries.
  • Simplified the title in docs/packages.md for consistency.

These changes collectively improve the usability, maintainability, and accuracy of the documentation.

xylar added 2 commits July 20, 2025 19:10
This merge also makes warnings report as errors when building
the docs and removes references to the autogenerated API.

Two unused pages have been removed.
This merge adds `index.md` files in each subdirectory of the docs
to help ensure that the table of contents is laid out intuitively.

The table providing the package catalog has been updated so that
different versions of dependencies for different python versions
are split into multiple rows for readability.
@xylar xylar self-assigned this Jul 20, 2025
@xylar xylar merged commit b347454 into E3SM-Project:main Jul 20, 2025
8 checks passed
@xylar xylar deleted the fix-docs branch July 20, 2025 17:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant